Shareware Overload Trio 2/Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO/dir36/schedtsk.zip/SCHEDTSK.DOC

Text File | 1993-12-07 | 25KB | 587 lines

SCHEDTSK and this documentation are Copyright (c) 1989-1993 Don Branson.
All Rights Reserved.


The programs (except for STRES.EXE and STPROC.EXE) may be distributed through
normal shareware/freeware channels.  STRES.EXE and STPROC.EXE are currently
available only through Simian Id Software of St. Louis, Missouri.



                          Table of Contents
                          -----------------


         I. Why SCHEDTSK?
            Covers typical uses for SCHEDTSK, to get you started.

        II. Concepts
            Defines and explains Tasks and Events.

       III. Task/Event Creation and Execution.
            An overview of how Tasks and Events are managed and run by the
            typical user.

        IV. Installing SCHEDTSK

         V. Programs
            A. EVENTMAN - Details of how EVENTMAN (Event Manager) is used
                          to define and manage Tasks and Events.

            B. STRUN    - Using STRUN to run the Events created.

            C. STPROC   - Using STPROC to load the background scheduler,
                          STRES.

            D. DTIME    - Describes the utility program, DTIME (Display Time).

            E. DOW      - Explains the use of the DOW (Day of Week) program.

         VI. Appendices
            A. Using your favorite editor to edit Tasks.

            B. Changing Tasks and Events while STRES is loaded.

            C. Upgrading from EVENTMAN 2.0 to SCHEDTSK 2.5.

            D. How STRES functions.

            E. Loading STRES into high memory.

            F. Using STRES with Microsoft Windows (tm).


I. Why SCHEDTSK?

        This package was developed originally to help a friend of mine who was
    the manager of the network where he worked.  He needed to run backups after
    hours, without being present himself.  The software with his backup unit did
    not support scheduled backups.  The SCHEDTSK software was designed from the
    beginning to be of general use, however, not just for network managers that
    need to schedule backups.  Now, most software that comes with tape backup
    units includes the ability to schedule backups for off-hours.  At the same
    time, the needs of network managers have increased in complexity, and these
    folks need to schedule other things as well, such as special reports,
    statistics reports, file transfers, and so forth.  The schedulers for the
    tape backup units can schedule only backups, and none of these other tasks.
    In addition, tape backup software can typically handle only the most simple
    scheduling.


        Many networks managers need the additional capabilities of a
    sophisticated scheduling program such as SCHEDTSK.  There are other
    alternative programs available, which can handle simple scheduling needs,
    but none have the capacity to handle the number of scheduled programs that
    SCHEDTSK can.  SCHEDTSK can schedule as many programs as you need.  They
    can be scheduled to run daily, weekly, monthly, even yearly.  They can be
    scheduled to run at an interval you specify, from 1 to 99,999 minutes.  They
    can also be scheduled to run a single time.  All scheduling is done through
    a full-screen program called EVENTMAN, which will take advantage of 43- or
    50-line screens, for those of you who use them. EVENTMAN also has complete,
    on-line, context-sensitive help.


        Once your programs are scheduled, all program execution is controlled by
    the program STRUN, which runs either on a stand-alone PC, or in a networked
    environment, on a workstation.  The workstation does not need to be a
    dedicated workstation.  STRUN displays the schedule of programs, sorted so
    that the next scheduled item is at the top of the list.


        All TSR functions are controlled by the programs STPROC and STRES.
    STPROC parses all the command line options for STRES.  It then loads STRES,
    the resident program, which can occupy as little as 2400 bytes of memory or
    less.  STRES coordinates program execution in conjunction with STRUN.


        While SCHEDTSK was mainly created for network managers, many other uses
    have been found for it.  I sometimes use it in conjunction with a terminal
    program to sign on to a BBS early in the morning, when noone else is on, and
    retrieve messages to a file.  A simple example is Daylight Savings time
    changes. Using SCHEDTSK, you can set your PC clock ahead in the spring, and
    back in the fall, automatically.


        As you use SCHEDTSK, you may find that there are many daily routines
    which you perform that it can handle for you. As you find new ways which
    SCHEDTSK works for you, please write and tell us how you are using it. This
    information can be included in future documentation, and will help other
    people as they use SCHEDTSK.



II. Concepts

        EVENTMAN works following two basic concepts, the TASK and the EVENT.  A
    Task is the process which you wish to run.  You can think of Task in the
    same way as a DOS batch program.  A Task performs, in order, the functions
    which you need done.  A Task has no time-related information stored with it.
    It is simply a set of related instructions, like a batch file.  The
    commands can be executable programs, or .BAT files.  When executing a .BAT
    file from a Task, you will need to use the CALL command, which is supported
    by DOS versions 4 and up, and is documented in your DOS manual.


        The second concept is the EVENT.  An Event consists of time information,
    plus a list of Tasks.  For example, an Event might be scheduled to run daily
    at 11:00 P.M., starting on January 1, 1994.  This Event would also include
    a list of Tasks to be run at that time.


        By separating the Task information and the Event information, general-
    purpose Tasks can be made which can be used by more than one Event.  See the
    Task BELL, or DISPTIME, for example, which are included in the SCHEDTSK
    package.  These and other Tasks can be seen by running the program EVENTMAN.
    Each Task in the list has an 8-character name, a 60-character description,
    and an associated file of DOS commands.  Each Event consists of a name, an
    interval, a starting time, and a list of Tasks to run.



III. Task/Event Creation and Execution

        While it is a good practice to make your Tasks small, it is not
    critical.  You may find that simple Tasks are more easily re-used by more
    than one Event than complex Tasks are.  Before setting up your own Tasks,
    you may want to take a look at some Tasks that are already defined.  The
    Tasks included with SCHEDTSK are set up to write any output to a log file
    named "C:\ST.LOG".  By using the Tasks DISPTIME and LINE, which display the
    date/time and a row of dashes, respectively, you can make this log file
    easier to scan.  The purpose of the log file is to keep a record of the
    successful execution of Tasks, and and also any problems which might occur.
    You won't necessarily require a log file in your environment, or you might
    want to redirect output to a printer.

        When your Tasks are defined, enter the Event list, and schedule your
    Events to run when needed.

        Once the Tasks and Events are set up, use STRUN to run the Tasks.  If
    you need to use the PC for something else, use STPROC to load STRES, which
    will wait in the background while you are using the PC for other purposes.
    You will normally run STRES via STPROC, not directly.  The exception to this
    is when you want to load STRES into high memory.  This is covered in
    Appendix E.



IV. Installing SCHEDTSK

        It is recommended that you install SCHEDTSK into a directory on a local
    hard drive.  The directory should be named SCHEDTSK.  All Tasks and Events
    should be defined in this directory.  This directory should also be added
    to your PATH.  Copy all files from the diskette or archive you received
    into the SCHEDTSK directory.

        To install SCHEDTSK, insert the diskette into drive A and type

            a:install

    at the DOS prompt.  Follow the instructions given by the installation
    program.  If your diskette is not the proper size for your A drive, you may
    also use your B drive.

        You may want to add STPROC or STRUN to your AUTOEXEC.BAT file, so that
    in the event of a power failure, your machine will come back up ready to
    run Events when the power comes back on.



V. Programs



    EVENTMAN
    --------

    Starting EVENTMAN

        EVENTMAN has no command-line options.  To run it, the SCHEDTSK
    directory should be the current directory.  Type EVENTMAN at the DOS prompt
    and press Enter.


    Keyboard

        The function keys available are always shown at the bottom of the
    screen.  Help is always available by pressing F1.


        In addition, the keys HOME, END, Page Up, Page Down, Insert, Delete,
    Backspace, Tab, Shift-Tab, and the arrow keys are functional in the Task
    Menu, the Event Menu, and data entry fields.


    The Task Menu

        The Task menu is displayed immediately upon entering EVENTMAN.  You
    may use the Tab or arrow keys to select a Task to work with.  Use Tab
    to move the cursor into the description, which may be changed right in
    the Task list.  When a Task is selected, use F2 to edit the command file
    for that Task.  Use F4 to delete the Task.  You will always be asked to
    confirmed deletes.  To create a new Task, press F3.  You will be asked
    to enter a name and description.  You will then be taken into the editor
    to edit the command file for the new Task.


        Appendix A discusses how you can use your own editor with EVENTMAN
    when editing Tasks.


    The Event Menu

        Pressing F5 takes you from the Task menu into the Event menu.  The
     same control keys (such as Tab) that work in the Task list work
     identically in the Event list.


        The function keys available are shown at the bottom of the screen.
    Use F2 whenever you want to make changes to an Event.  Use F3 to add an
    Event, and F4 to delete an Event.


        Whenever you add an Event, you will be asked to give it an 8-character
    name.  You will need to indicate the interval when the Event should be run
    by selecting an Event type.  Your options are D (daily), W (weekly),
    M (monthly), Y (yearly), S (single run, no repeats), and O (other -
    interval specified in minutes.)  If you select O, you will also be prompted
    to enter the number of minutes between runs.  For example, to run a process
    every hour, enter O as the Event type, and 60 as the interval in minutes.


        You will also need to enter a starting date and time.  The date may be
    any date which DOS supports.  This range covers years 1980-2099.  The time
    is entered in 24-hour format.


        Each Event also requires a list of Tasks which will be executed as
    specified.  The Task names are separated by commas, and each Task must be a
    valid Task from the Task list.  Press F6 to save changes to the Event,
    or ESC to cancel.


        F4 is used to delete Events.  You will be asked to confirm the delete.



    STRUN
    -----

        STRUN is the program which controls the execution of all Events.  This
    program is the program that you use to run Events, and it is also the
    program which STRES (the TSR) runs when an Event is scheduled to run.
    STRUN maintains a list of Events in order by date and time, with the next
    scheduled Event at the top of the list.  The current time is also displayed
    so that you can see both the current time and the time of the next Event
    on the screen together.


        When STRUN runs an Event, it updates the list of Events on disk with
    the date and time when that Event will again be run.  This date and time
    will be reflected when you use EVENTMAN to view the Events.  STRUN also
    updates its list of Events, so that the next Event is moved to the top of
    the Event list.


        STRUN has a few command-line options, which may be chosen using a
    slash (/), a dash (-), or no prefix at all.  For example, STRUN with the
    help option (H) may be run any of these formats:

        strun /h
        strun -h
        strun h


        Options do not need to be separated by spaces.  These are the command-
    line options for STRUN:

        H - This option displays the list of options for STRUN.

        Q - Quiet mode.  This option turns off the full-screen display.  In
            this mode, STRUN runs all Events that are ready to run, then exits
            quietly.  This mode is mainly used by STRES, to run current Events.

        P - Run Past processes.  This option runs Events whose date and/or time
            have already passed without execution.  This situation may occur if
            your system was off when an Event was scheduled, or if some program
            prevented the execution of STRUN when an Event was scheduled.  This
            option is also mainly for use by STRES.

        F - Force run.  This option forces to STRUN to run even if TSRPROC
            is determined to be running.  TSRPROC is an old version of STRES,
            and STRUN should not execute when it is running.  This option is
            needed in case STRUN decides that TSRPROC is running when it is
            not.


        When STRUN begins execution, it needs to bring all processes up-to-
    date.  If Option P is selected, it will run each Event for each scheduled
    interval until the Event is brought up to the current date and time.



    STPROC
    ------

        STPROC is the loader program for the TSR, STRES.  This program reads
    the command line parameters, sets all options, then sets up and loads
    STRES.  STRES is the program that stays resident in memory waiting for the
    next Event.  STPROC can also be used to query the status of STRES.  When
    STRES is loaded, it runs STRUN in order to establish the date and time of
    the next Event.


        STPROC has two sets of options.  The first are options that are used
    when STRES is started.  The format of the options is the same as for STRUN,
    so you may use option prefixes of /, -, or nothing.  The options are:


        H - This option displays the list of options for STPROC.


        V - Verbose mode.  This option sets Verbose mode on.  When STRES
            is loaded, it will display information about its status.

        P - Run past processes upon initialization.  This flag is passed to
            STRUN when it is loaded by STRES at initialization.

        C - This flag is used to set the Check frequency.  By default, STRES
            checks every 5 seconds to see what the current time is, when the
            time of the next Event is near or has passed.  See Appendix D for
            an explanation of the algorithm that STRES uses for checking the
            time.  Here is the format for this option:

                STPROC c2

        S - This option sets the stack size used by STRES.  The default stack
            size is 256 bytes.  The stack size can be set anywhere from 32
            bytes to 32767 bytes.  The size of the stack directly effects the
            size of the resident program.  The minimum recommended size is 128
            bytes.  Using a smaller size may cause erratic behavior.  This is
            the format for this option:

                STPROC s128


        The second set of command-line options are only valid when STRES has
    already been made resident.  These options are:

        U - Unload STRES.  This option will remove STRES from memory unless
            other TSR's have been loaded after it which use the same interrupts
            which it uses.

        Q - Query status of STRES.  This option displays the current date and
            time, and the date and time of the next Event, as recorded by
            STRES.


        When STRES is resident in memory, Alt-LeftShift will cause STRUN to
    pop up and display the current Event list.  See Appendix D for limitations
    on pop-ups.



    DTIME
    -----

        DTIME is a simple program, but it is handy to have when using SCHEDTSK.
    This program displays the current date and time on a single line.  There
    are no command-line options.  This program is demonstrated in the Task
    DISPTIME, which is provided in the SCHEDTSK package.


    DOW
    ---

        This is another small program (8 bytes!), but one which can add
    tremendous flexibilty to SCHEDTSK.  It simply returns the Day Of Week as
    a DOS error code.  This error code can then be used in a .BAT file.  The
    following .BAT file demonstrates how this is done.  It is a program that
    I use for daily tape backups.  It will run a backup every day except
    Sunday.  CBACKUP, which is executed by this .BAT file, is the actual tape
    backup program:



         echo off
         dow
         if errorlevel 6 goto saturday
         if errorlevel 5 goto friday
         if errorlevel 4 goto thursday
         if errorlevel 3 goto wednesday
         if errorlevel 2 goto tuesday
         if errorlevel 1 goto monday
         if errorlevel 0 goto sunday
         goto exit
         :sunday
         echo Today is Sunday - Don't do a backup
         goto exit
         :monday
         echo Today is Monday - Do a backup
         cbackup
         goto exit
         :tuesday
         echo Today is Tuesday - Do a backup
         cbackup
         goto exit
         :wednesday
         echo Today is Wednesday - Do a backup
         cbackup
         goto exit
         :thursday
         echo Today is Thursday - Do a backup
         cbackup
         goto exit
         :friday
         echo Today is Friday - Do a backup
         cbackup
         goto exit
         :saturday
         echo Today is Saturday - Do a backup
         cbackup
         goto exit
         :exit
         exit
         echo Procedure cbackup complete.



VI. Appendices



Appendix A: Using your favorite editor to edit Tasks

        EVENTMAN is set up so that you can specify an editor to use when
    editing Task command files.  EVENTMAN will first look for the Editor SBE,
    an editor formerly available through Simian Id Software.  If SBE is not
    present, EVENTMAN will try to execute EDIT, the editor that comes with
    MS-DOS 5 and later versions.  Finally, EVENTMAN will try to run EDLIN, the
    line editor available with all versions of MS-DOS.


        To override this behavior, you may set a DOS environment variable with
    the path and name of the editor you want to use.  The name of the variable
    is EDITOR.  This may be set at the DOS prompt or in your AUTOEXEC.BAT file.
    For example, if the name of your favorite editor is FAV_EDIT, and it is in
    the directory C:\MY_FAVS, type:

        SET EDITOR=C:\MY_FAVS\FAV_EDIT

    at the DOS prompt, or enter that line into your AUTOEXEC.BAT file.  Now
    when you use F2 to edit a Task command file, your editor will be used.



Appendix B: Changing Tasks and Events while STRES is loaded

        EVENTMAN can be loaded and run while STRES is resident in memory.
    After you change any process, you should pop-up STRUN, then exit, in order
    to re-initialize the Event date within STRES.



Appendix C: Upgrading from EVENTMAN 2.0 to SCHEDTSK 2.5

        For users of prior version of SCHEDTSK (formerly known as EVENTMAN),
    you should run the new EVENTMAN program, which will convert files to the
    format used by SCHEDTSK.  The concept of a Process in prior versions has
    become the concept of an Event.  The concept of an Event in the prior
    versions has become a Task.  Task and Event more appropriately describe
    the nature of these two concepts.


       The most significant change you will notice in the newest version of
    SCHEDTSK is that the TSR is significantly smaller.  When STPROC is used
    with the smallest recommended stack, STRES occupies only 2352 bytes of
    your PC's memory.



Appendix D: How STRES functions

        STRES is normally loaded using STPROC.  STPROC parses the command
    options, setting flags, then writes these flags to the file ST_PARM.000,
    which STRES will read.  STPROC then loads STRES, passing the path and name
    of the file with the flags.


        STRES is a TSR (Terminate and Stay Resident) program.  Once loaded, it
    occupies typically 2.3K of memory.  When it is started, it also runs STRUN
    as a subprogram.  STRUN then reads the Task and Event lists, and determines
    the time of the next Event, which it then communicates to STRES via an
    interrupt.  Dates and times in STRES are stored in the DOS system format,
    so that STRES can quickly check them against the current date and time,
    using a minimum of CPU time and stack space.


        STRES determines how long it will be until the next Event.  If the next
    Event is more that a day off, it will set a timer so that it doesn't check
    again until 24 hours have passed, thus minimizing CPU usage.  If the time
    is less than hour, STRES will calculate the amount of time to wait and
    check again.  It always underestimates, so that Events are not missed due
    to this process.  When the timer is set, STRES uses very little CPU in
    checking the time.  It is attached to the timer interrupt, and merely
    decrements a counter, then returns if the counter is not zero.  Every
    effort has been made to make STRES as efficient as possible.


        When an Event is ready to run, STRES needs to invoke STRUN to actually
    run the processes.  Since the code to manage and control the running of
    processes is fairly large, it is important to only load it when it is time
    to run an Event.  When an Event is ready to run, STRES determines if the
    system state is currently at the DOS prompt.  If not, it will sleep the
    number of seconds determined by the STPROC 'C' option, then try again.  It
    will continue in this fashion until it can run STRUN.  STRES cannot
    absolutely determine that it is at a DOS prompt.  If you are at the prompt
    of the DATE or TIME command, STRES will think that you are at a DOS prompt
    when you are not.


       In order to load STRUN, STRES stuffs keystrokes into the keyboard buffer.
    The first character that STRES stuffs is the ESC character, so that the
    DOS command line will be cleared of anything entered.  The command to run
    STRUN is then stuffed, and STRUN executes.  When STRES runs STRUN, it always
    uses the 'Q' option, which tells STRUN to run in quiet mode, then exit.


        When STRUN has completed the running of processes, it determines the
    date and time of the next Event, and communicates this to STRES via an
    interrupt.



Appendix E: Loading STRES into high memory

        STRES is typically loaded into the lower 640K of DOS memory, but it
    is possible to load it into high memory indirectly.  This is how it is
    done.  First, use STPROC to load STRES with the options you want.  This
    will create the file ST_PARM.000 in the SCHEDTSK directory.  Next use the
    command 'STPROC U' to unload STRES.  Finally, re-load STRES directly,
    using the DOS LOADHIGH command, and giving the name of the parameter file
    on the command line.  Here is a typical use, where the short form of the
    LOADHIGH command, 'LH', has been used:


        \schedtsk\stproc vs128
        \schedtsk\stproc u
        lh \schedtsk\stres \schedtsk\st_parm.000



Appendix F: Using STRES with Microsoft Windows

        When using STRES with Microsoft Windows, STRES should be loaded before
    Windows is loaded.  You will need to open a DOS prompt where it can pop-up
    STRUN.  When using STRES in this fashion, you should use the 'C' option on
    STPROC to specifiy that it check every second, so that it will be sure to
    pop-up when an Event occurs.  If you do not, STRES may never check the time
    at the same instant when Windows has given it CPU.  Even so, Events may run
    late when STRES is used in this fashion.



Trademarks

Microsoft, MS-DOS and Windows are registered trademarks of the Microsoft
Corporation.